/*
 * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.security;

import java.util.*;

import java.security.spec.AlgorithmParameterSpec;

import java.security.Provider.Service;

import sun.security.jca.*;
import sun.security.jca.GetInstance.Instance;
import sun.security.util.Debug;

/**
 * The KeyPairGenerator class is used to generate pairs of
 * public and private keys. Key pair generators are constructed using the
 * {@code getInstance} factory methods (static methods that
 * return instances of a given class).
 *
 * <p>A Key pair generator for a particular algorithm creates a public/private
 * key pair that can be used with this algorithm. It also associates
 * algorithm-specific parameters with each of the generated keys.
 *
 * <p>There are two ways to generate a key pair: in an algorithm-independent
 * manner, and in an algorithm-specific manner.
 * The only difference between the two is the initialization of the object:
 *
 * <ul>
 * <li><b>Algorithm-Independent Initialization</b>
 * <p>All key pair generators share the concepts of a keysize and a
 * source of randomness. The keysize is interpreted differently for different
 * algorithms (e.g., in the case of the <i>DSA</i> algorithm, the keysize
 * corresponds to the length of the modulus).
 * There is an
 * {@link #initialize(int, java.security.SecureRandom) initialize}
 * method in this KeyPairGenerator class that takes these two universally
 * shared types of arguments. There is also one that takes just a
 * {@code keysize} argument, and uses the {@code SecureRandom}
 * implementation of the highest-priority installed provider as the source
 * of randomness. (If none of the installed providers supply an implementation
 * of {@code SecureRandom}, a system-provided source of randomness is
 * used.)
 *
 * <p>Since no other parameters are specified when you call the above
 * algorithm-independent {@code initialize} methods, it is up to the
 * provider what to do about the algorithm-specific parameters (if any) to be
 * associated with each of the keys.
 *
 * <p>If the algorithm is the <i>DSA</i> algorithm, and the keysize (modulus
 * size) is 512, 768, or 1024, then the <i>Sun</i> provider uses a set of
 * precomputed values for the {@code p}, {@code q}, and
 * {@code g} parameters. If the modulus size is not one of the above
 * values, the <i>Sun</i> provider creates a new set of parameters. Other
 * providers might have precomputed parameter sets for more than just the
 * three modulus sizes mentioned above. Still others might not have a list of
 * precomputed parameters at all and instead always create new parameter sets.
 *
 * <li><b>Algorithm-Specific Initialization</b>
 * <p>For situations where a set of algorithm-specific parameters already
 * exists (e.g., so-called <i>community parameters</i> in DSA), there are two
 * {@link #initialize(java.security.spec.AlgorithmParameterSpec)
 * initialize} methods that have an {@code AlgorithmParameterSpec}
 * argument. One also has a {@code SecureRandom} argument, while the
 * the other uses the {@code SecureRandom}
 * implementation of the highest-priority installed provider as the source
 * of randomness. (If none of the installed providers supply an implementation
 * of {@code SecureRandom}, a system-provided source of randomness is
 * used.)
 * </ul>
 *
 * <p>In case the client does not explicitly initialize the KeyPairGenerator
 * (via a call to an {@code initialize} method), each provider must
 * supply (and document) a default initialization.
 * For example, the <i>Sun</i> provider uses a default modulus size (keysize)
 * of 1024 bits.
 *
 * <p>Note that this class is abstract and extends from
 * {@code KeyPairGeneratorSpi} for historical reasons.
 * Application developers should only take notice of the methods defined in
 * this {@code KeyPairGenerator} class; all the methods in
 * the superclass are intended for cryptographic service providers who wish to
 * supply their own implementations of key pair generators.
 *
 * <p> Every implementation of the Java platform is required to support the
 * following standard {@code KeyPairGenerator} algorithms and keysizes in
 * parentheses:
 * <ul>
 * <li>{@code DiffieHellman} (1024)</li>
 * <li>{@code DSA} (1024)</li>
 * <li>{@code RSA} (1024, 2048)</li>
 * </ul>
 * These algorithms are described in the <a href=
 * "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyPairGenerator">
 * KeyPairGenerator section</a> of the
 * Java Cryptography Architecture Standard Algorithm Name Documentation.
 * Consult the release documentation for your implementation to see if any
 * other algorithms are supported.
 *
 * @author Benjamin Renaud
 * @see java.security.spec.AlgorithmParameterSpec
 */

public abstract class KeyPairGenerator extends KeyPairGeneratorSpi {

  private static final Debug pdebug =
      Debug.getInstance("provider", "Provider");
  private static final boolean skipDebug =
      Debug.isOn("engine=") && !Debug.isOn("keypairgenerator");

  private final String algorithm;

  // The provider
  Provider provider;

  /**
   * Creates a KeyPairGenerator object for the specified algorithm.
   *
   * @param algorithm the standard string name of the algorithm. See the KeyPairGenerator section in
   * the <a href= "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyPairGenerator">
   * Java Cryptography Architecture Standard Algorithm Name Documentation</a> for information about
   * standard algorithm names.
   */
  protected KeyPairGenerator(String algorithm) {
    this.algorithm = algorithm;
  }

  /**
   * Returns the standard name of the algorithm for this key pair generator.
   * See the KeyPairGenerator section in the <a href=
   * "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyPairGenerator">
   * Java Cryptography Architecture Standard Algorithm Name Documentation</a>
   * for information about standard algorithm names.
   *
   * @return the standard string name of the algorithm.
   */
  public String getAlgorithm() {
    return this.algorithm;
  }

  private static KeyPairGenerator getInstance(Instance instance,
      String algorithm) {
    KeyPairGenerator kpg;
    if (instance.impl instanceof KeyPairGenerator) {
      kpg = (KeyPairGenerator) instance.impl;
    } else {
      KeyPairGeneratorSpi spi = (KeyPairGeneratorSpi) instance.impl;
      kpg = new Delegate(spi, algorithm);
    }
    kpg.provider = instance.provider;

    if (!skipDebug && pdebug != null) {
      pdebug.println("KeyPairGenerator." + algorithm +
          " algorithm from: " + kpg.provider.getName());
    }

    return kpg;
  }

  /**
   * Returns a KeyPairGenerator object that generates public/private
   * key pairs for the specified algorithm.
   *
   * <p> This method traverses the list of registered security Providers,
   * starting with the most preferred Provider.
   * A new KeyPairGenerator object encapsulating the
   * KeyPairGeneratorSpi implementation from the first
   * Provider that supports the specified algorithm is returned.
   *
   * <p> Note that the list of registered providers may be retrieved via
   * the {@link Security#getProviders() Security.getProviders()} method.
   *
   * @param algorithm the standard string name of the algorithm. See the KeyPairGenerator section in
   * the <a href= "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyPairGenerator">
   * Java Cryptography Architecture Standard Algorithm Name Documentation</a> for information about
   * standard algorithm names.
   * @return the new KeyPairGenerator object.
   * @throws NoSuchAlgorithmException if no Provider supports a KeyPairGeneratorSpi implementation
   * for the specified algorithm.
   * @see Provider
   */
  public static KeyPairGenerator getInstance(String algorithm)
      throws NoSuchAlgorithmException {
    List<Service> list =
        GetInstance.getServices("KeyPairGenerator", algorithm);
    Iterator<Service> t = list.iterator();
    if (t.hasNext() == false) {
      throw new NoSuchAlgorithmException
          (algorithm + " KeyPairGenerator not available");
    }
    // find a working Spi or KeyPairGenerator subclass
    NoSuchAlgorithmException failure = null;
    do {
      Service s = t.next();
      try {
        Instance instance =
            GetInstance.getInstance(s, KeyPairGeneratorSpi.class);
        if (instance.impl instanceof KeyPairGenerator) {
          return getInstance(instance, algorithm);
        } else {
          return new Delegate(instance, t, algorithm);
        }
      } catch (NoSuchAlgorithmException e) {
        if (failure == null) {
          failure = e;
        }
      }
    } while (t.hasNext());
    throw failure;
  }

  /**
   * Returns a KeyPairGenerator object that generates public/private
   * key pairs for the specified algorithm.
   *
   * <p> A new KeyPairGenerator object encapsulating the
   * KeyPairGeneratorSpi implementation from the specified provider
   * is returned.  The specified provider must be registered
   * in the security provider list.
   *
   * <p> Note that the list of registered providers may be retrieved via
   * the {@link Security#getProviders() Security.getProviders()} method.
   *
   * @param algorithm the standard string name of the algorithm. See the KeyPairGenerator section in
   * the <a href= "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyPairGenerator">
   * Java Cryptography Architecture Standard Algorithm Name Documentation</a> for information about
   * standard algorithm names.
   * @param provider the string name of the provider.
   * @return the new KeyPairGenerator object.
   * @throws NoSuchAlgorithmException if a KeyPairGeneratorSpi implementation for the specified
   * algorithm is not available from the specified provider.
   * @throws NoSuchProviderException if the specified provider is not registered in the security
   * provider list.
   * @throws IllegalArgumentException if the provider name is null or empty.
   * @see Provider
   */
  public static KeyPairGenerator getInstance(String algorithm,
      String provider)
      throws NoSuchAlgorithmException, NoSuchProviderException {
    Instance instance = GetInstance.getInstance("KeyPairGenerator",
        KeyPairGeneratorSpi.class, algorithm, provider);
    return getInstance(instance, algorithm);
  }

  /**
   * Returns a KeyPairGenerator object that generates public/private
   * key pairs for the specified algorithm.
   *
   * <p> A new KeyPairGenerator object encapsulating the
   * KeyPairGeneratorSpi implementation from the specified Provider
   * object is returned.  Note that the specified Provider object
   * does not have to be registered in the provider list.
   *
   * @param algorithm the standard string name of the algorithm. See the KeyPairGenerator section in
   * the <a href= "{@docRoot}/../technotes/guides/security/StandardNames.html#KeyPairGenerator">
   * Java Cryptography Architecture Standard Algorithm Name Documentation</a> for information about
   * standard algorithm names.
   * @param provider the provider.
   * @return the new KeyPairGenerator object.
   * @throws NoSuchAlgorithmException if a KeyPairGeneratorSpi implementation for the specified
   * algorithm is not available from the specified Provider object.
   * @throws IllegalArgumentException if the specified provider is null.
   * @see Provider
   * @since 1.4
   */
  public static KeyPairGenerator getInstance(String algorithm,
      Provider provider) throws NoSuchAlgorithmException {
    Instance instance = GetInstance.getInstance("KeyPairGenerator",
        KeyPairGeneratorSpi.class, algorithm, provider);
    return getInstance(instance, algorithm);
  }

  /**
   * Returns the provider of this key pair generator object.
   *
   * @return the provider of this key pair generator object
   */
  public final Provider getProvider() {
    disableFailover();
    return this.provider;
  }

  void disableFailover() {
    // empty, overridden in Delegate
  }

  /**
   * Initializes the key pair generator for a certain keysize using
   * a default parameter set and the {@code SecureRandom}
   * implementation of the highest-priority installed provider as the source
   * of randomness.
   * (If none of the installed providers supply an implementation of
   * {@code SecureRandom}, a system-provided source of randomness is
   * used.)
   *
   * @param keysize the keysize. This is an algorithm-specific metric, such as modulus length,
   * specified in number of bits.
   * @throws InvalidParameterException if the {@code keysize} is not supported by this
   * KeyPairGenerator object.
   */
  public void initialize(int keysize) {
    initialize(keysize, JCAUtil.getSecureRandom());
  }

  /**
   * Initializes the key pair generator for a certain keysize with
   * the given source of randomness (and a default parameter set).
   *
   * @param keysize the keysize. This is an algorithm-specific metric, such as modulus length,
   * specified in number of bits.
   * @param random the source of randomness.
   * @throws InvalidParameterException if the {@code keysize} is not supported by this
   * KeyPairGenerator object.
   * @since 1.2
   */
  public void initialize(int keysize, SecureRandom random) {
    // This does nothing, because either
    // 1. the implementation object returned by getInstance() is an
    //    instance of KeyPairGenerator which has its own
    //    initialize(keysize, random) method, so the application would
    //    be calling that method directly, or
    // 2. the implementation returned by getInstance() is an instance
    //    of Delegate, in which case initialize(keysize, random) is
    //    overridden to call the corresponding SPI method.
    // (This is a special case, because the API and SPI method have the
    // same name.)
  }

  /**
   * Initializes the key pair generator using the specified parameter
   * set and the {@code SecureRandom}
   * implementation of the highest-priority installed provider as the source
   * of randomness.
   * (If none of the installed providers supply an implementation of
   * {@code SecureRandom}, a system-provided source of randomness is
   * used.).
   *
   * <p>This concrete method has been added to this previously-defined
   * abstract class.
   * This method calls the KeyPairGeneratorSpi
   * {@link KeyPairGeneratorSpi#initialize(
   *java.security.spec.AlgorithmParameterSpec,
   * java.security.SecureRandom) initialize} method,
   * passing it {@code params} and a source of randomness (obtained
   * from the highest-priority installed provider or system-provided if none
   * of the installed providers supply one).
   * That {@code initialize} method always throws an
   * UnsupportedOperationException if it is not overridden by the provider.
   *
   * @param params the parameter set used to generate the keys.
   * @throws InvalidAlgorithmParameterException if the given parameters are inappropriate for this
   * key pair generator.
   * @since 1.2
   */
  public void initialize(AlgorithmParameterSpec params)
      throws InvalidAlgorithmParameterException {
    initialize(params, JCAUtil.getSecureRandom());
  }

  /**
   * Initializes the key pair generator with the given parameter
   * set and source of randomness.
   *
   * <p>This concrete method has been added to this previously-defined
   * abstract class.
   * This method calls the KeyPairGeneratorSpi {@link
   * KeyPairGeneratorSpi#initialize(
   *java.security.spec.AlgorithmParameterSpec,
   * java.security.SecureRandom) initialize} method,
   * passing it {@code params} and {@code random}.
   * That {@code initialize}
   * method always throws an
   * UnsupportedOperationException if it is not overridden by the provider.
   *
   * @param params the parameter set used to generate the keys.
   * @param random the source of randomness.
   * @throws InvalidAlgorithmParameterException if the given parameters are inappropriate for this
   * key pair generator.
   * @since 1.2
   */
  public void initialize(AlgorithmParameterSpec params,
      SecureRandom random)
      throws InvalidAlgorithmParameterException {
    // This does nothing, because either
    // 1. the implementation object returned by getInstance() is an
    //    instance of KeyPairGenerator which has its own
    //    initialize(params, random) method, so the application would
    //    be calling that method directly, or
    // 2. the implementation returned by getInstance() is an instance
    //    of Delegate, in which case initialize(params, random) is
    //    overridden to call the corresponding SPI method.
    // (This is a special case, because the API and SPI method have the
    // same name.)
  }

  /**
   * Generates a key pair.
   *
   * <p>If this KeyPairGenerator has not been initialized explicitly,
   * provider-specific defaults will be used for the size and other
   * (algorithm-specific) values of the generated keys.
   *
   * <p>This will generate a new key pair every time it is called.
   *
   * <p>This method is functionally equivalent to
   * {@link #generateKeyPair() generateKeyPair}.
   *
   * @return the generated key pair
   * @since 1.2
   */
  public final KeyPair genKeyPair() {
    return generateKeyPair();
  }

  /**
   * Generates a key pair.
   *
   * <p>If this KeyPairGenerator has not been initialized explicitly,
   * provider-specific defaults will be used for the size and other
   * (algorithm-specific) values of the generated keys.
   *
   * <p>This will generate a new key pair every time it is called.
   *
   * <p>This method is functionally equivalent to
   * {@link #genKeyPair() genKeyPair}.
   *
   * @return the generated key pair
   */
  public KeyPair generateKeyPair() {
    // This does nothing (except returning null), because either:
    //
    // 1. the implementation object returned by getInstance() is an
    //    instance of KeyPairGenerator which has its own implementation
    //    of generateKeyPair (overriding this one), so the application
    //    would be calling that method directly, or
    //
    // 2. the implementation returned by getInstance() is an instance
    //    of Delegate, in which case generateKeyPair is
    //    overridden to invoke the corresponding SPI method.
    //
    // (This is a special case, because in JDK 1.1.x the generateKeyPair
    // method was used both as an API and a SPI method.)
    return null;
  }


    /*
     * The following class allows providers to extend from KeyPairGeneratorSpi
     * rather than from KeyPairGenerator. It represents a KeyPairGenerator
     * with an encapsulated, provider-supplied SPI object (of type
     * KeyPairGeneratorSpi).
     * If the provider implementation is an instance of KeyPairGeneratorSpi,
     * the getInstance() methods above return an instance of this class, with
     * the SPI object encapsulated.
     *
     * Note: All SPI methods from the original KeyPairGenerator class have been
     * moved up the hierarchy into a new class (KeyPairGeneratorSpi), which has
     * been interposed in the hierarchy between the API (KeyPairGenerator)
     * and its original parent (Object).
     */

  //
  // error failover notes:
  //
  //  . we failover if the implementation throws an error during init
  //    by retrying the init on other providers
  //
  //  . we also failover if the init succeeded but the subsequent call
  //    to generateKeyPair() fails. In order for this to work, we need
  //    to remember the parameters to the last successful call to init
  //    and initialize() the next spi using them.
  //
  //  . although not specified, KeyPairGenerators could be thread safe,
  //    so we make sure we do not interfere with that
  //
  //  . failover is not available, if:
  //    . getInstance(algorithm, provider) was used
  //    . a provider extends KeyPairGenerator rather than
  //      KeyPairGeneratorSpi (JDK 1.1 style)
  //    . once getProvider() is called
  //

  private static final class Delegate extends KeyPairGenerator {

    // The provider implementation (delegate)
    private volatile KeyPairGeneratorSpi spi;

    private final Object lock = new Object();

    private Iterator<Service> serviceIterator;

    private final static int I_NONE = 1;
    private final static int I_SIZE = 2;
    private final static int I_PARAMS = 3;

    private int initType;
    private int initKeySize;
    private AlgorithmParameterSpec initParams;
    private SecureRandom initRandom;

    // constructor
    Delegate(KeyPairGeneratorSpi spi, String algorithm) {
      super(algorithm);
      this.spi = spi;
    }

    Delegate(Instance instance, Iterator<Service> serviceIterator,
        String algorithm) {
      super(algorithm);
      spi = (KeyPairGeneratorSpi) instance.impl;
      provider = instance.provider;
      this.serviceIterator = serviceIterator;
      initType = I_NONE;

      if (!skipDebug && pdebug != null) {
        pdebug.println("KeyPairGenerator." + algorithm +
            " algorithm from: " + provider.getName());
      }
    }

    /**
     * Update the active spi of this class and return the next
     * implementation for failover. If no more implemenations are
     * available, this method returns null. However, the active spi of
     * this class is never set to null.
     */
    private KeyPairGeneratorSpi nextSpi(KeyPairGeneratorSpi oldSpi,
        boolean reinit) {
      synchronized (lock) {
        // somebody else did a failover concurrently
        // try that spi now
        if ((oldSpi != null) && (oldSpi != spi)) {
          return spi;
        }
        if (serviceIterator == null) {
          return null;
        }
        while (serviceIterator.hasNext()) {
          Service s = serviceIterator.next();
          try {
            Object inst = s.newInstance(null);
            // ignore non-spis
            if (inst instanceof KeyPairGeneratorSpi == false) {
              continue;
            }
            if (inst instanceof KeyPairGenerator) {
              continue;
            }
            KeyPairGeneratorSpi spi = (KeyPairGeneratorSpi) inst;
            if (reinit) {
              if (initType == I_SIZE) {
                spi.initialize(initKeySize, initRandom);
              } else if (initType == I_PARAMS) {
                spi.initialize(initParams, initRandom);
              } else if (initType != I_NONE) {
                throw new AssertionError
                    ("KeyPairGenerator initType: " + initType);
              }
            }
            provider = s.getProvider();
            this.spi = spi;
            return spi;
          } catch (Exception e) {
            // ignore
          }
        }
        disableFailover();
        return null;
      }
    }

    void disableFailover() {
      serviceIterator = null;
      initType = 0;
      initParams = null;
      initRandom = null;
    }

    // engine method
    public void initialize(int keysize, SecureRandom random) {
      if (serviceIterator == null) {
        spi.initialize(keysize, random);
        return;
      }
      RuntimeException failure = null;
      KeyPairGeneratorSpi mySpi = spi;
      do {
        try {
          mySpi.initialize(keysize, random);
          initType = I_SIZE;
          initKeySize = keysize;
          initParams = null;
          initRandom = random;
          return;
        } catch (RuntimeException e) {
          if (failure == null) {
            failure = e;
          }
          mySpi = nextSpi(mySpi, false);
        }
      } while (mySpi != null);
      throw failure;
    }

    // engine method
    public void initialize(AlgorithmParameterSpec params,
        SecureRandom random) throws InvalidAlgorithmParameterException {
      if (serviceIterator == null) {
        spi.initialize(params, random);
        return;
      }
      Exception failure = null;
      KeyPairGeneratorSpi mySpi = spi;
      do {
        try {
          mySpi.initialize(params, random);
          initType = I_PARAMS;
          initKeySize = 0;
          initParams = params;
          initRandom = random;
          return;
        } catch (Exception e) {
          if (failure == null) {
            failure = e;
          }
          mySpi = nextSpi(mySpi, false);
        }
      } while (mySpi != null);
      if (failure instanceof RuntimeException) {
        throw (RuntimeException) failure;
      }
      // must be an InvalidAlgorithmParameterException
      throw (InvalidAlgorithmParameterException) failure;
    }

    // engine method
    public KeyPair generateKeyPair() {
      if (serviceIterator == null) {
        return spi.generateKeyPair();
      }
      RuntimeException failure = null;
      KeyPairGeneratorSpi mySpi = spi;
      do {
        try {
          return mySpi.generateKeyPair();
        } catch (RuntimeException e) {
          if (failure == null) {
            failure = e;
          }
          mySpi = nextSpi(mySpi, true);
        }
      } while (mySpi != null);
      throw failure;
    }
  }

}
